클라이언트 디렉토리와 화면 구조 이해하기

결론부터 예기하면 다음과 같습니다

• HandStack 은 웹 개발 프레임워크 입니다.
• 모듈의 wwwroot 디렉토리 구조와 웹 브라우저에서 요청하는 경로와 어떻게 매칭되는지 이해합니다.
• 프론트엔드 자원(assets, lib, css, js, img)의 역할을 파악합니다.
• 화면을 구성하는 핵심 디렉토리인 view의 구조를 학습합니다.
• wwwroot 모듈의 클라이언트 디렉토리는 웹 사이트의 큰 방들이고, 이 외의 모듈의 디렉토리는 그 방 안에 있는 자원들이라고 생각하시면 됩니다.
• 자원들은 화면에서 직접 사용 할 수 있습니다.

wwwroot 디렉토리: 모듈의 기본 디렉토리

wwwroot는 클라이언트 측의 모든 로직과 리소스가 이 디렉토리를 중심으로 구성됩니다.

$(HANDSTACK_SRC)/2.Modules/[모듈 ID]/wwwroot

• assets/
• lib/
• css/
• js/
• img/

http://localhost:8421/[모듈 ID]/**.*

assets/ - 공용 정적 리소스

모듈 공통 또는 외부에서 사용하는 정적 리소스를 저장하는 공간입니다.

• 예시
  • 미디어, SVG 파일, 플러그인 관련 리소스
• 특징
  • 다른 모듈이나 페이지에서도 공통으로 참조될 수 있도록 구성합니다.
  • 범용적으로 사용되는 자산을 배치하여 재사용성을 높입니다.

lib/ - 외부 라이브러리

모듈 내에서 사용중인 외부 프론트엔드 라이브러리의 원본 파일을 저장합니다.

• 예시
  • /lib/jquery/jquery.min.js
  • /lib/bootstrap/css/bootstrap.min.css
• 특징
  • 주로 cdnjs, jsdelivr 같은 CDN에서 제공하는 라이브러리로 구성됩니다.
  • $(HANDSTACK_SRC)/libman.json 파일을 통해 관리됩니다.

css/ - 스타일 시트

모듈 내에서 적용되는 CSS 파일을 저장합니다.

• 예시
  • /css/site.css (전역 스타일)
  • /[모듈 ID]/css/module.css (모듈별 스타일)
• 특징
  • 전역 스타일과 특정 모듈/페이지 스타일로 나누어 관리할 수 있습니다.
  • 사용자 정의 테마나 디자인 커스터마이징에 활용됩니다.

js/ - 공통 스크립트

모듈 내에서 클라이언트 측 기능을 담당하는 공통 JavaScript 파일을 저장합니다.

• 예시
  • /js/module-user.js
  • /js/utilities.js
• 특징
  • 여러 화면에서 공통으로 사용하는 유틸리티 함수나 로직을 포함합니다.
  • 수동으로 관리하거나 커스터마이징된 라이브러리를 직접 포함할 수 있습니다.

img/ - 이미지 파일

모듈 내에서 UI에 사용되는 로고, 아이콘, 배경 등의 이미지 파일을 보관합니다.

• 예시
  • /img/logo.png
  • /img/empty-state.svg
• 특징
  • 정적 콘텐츠로서 페이지 로딩 시 브라우저에 직접 제공되는 시각 자료입니다.

wwwroot 모듈의 wwwroot 디렉토리: 웹의 기본 디렉토리

wwwroot는 클라이언트 측의 공통 로직과 리소스가 이 디렉토리를 중심으로 구성됩니다.

$(HANDSTACK_SRC)/2.Modules/wwwroot/wwwroot

• 클라이언트 디렉토리 구조/
• font/
• sample/
• uicontrols/

http://localhost:8421/**.*

syn.js 공통 스크립트 디렉토리 및 번들링

$(HANDSTACK_SRC)/1.WebHost/ack/wwwroot/assets/src

cd $(HANDSTACK_SRC)/1.WebHost/ack
npm i
gulp

$(HANDSTACK_SRC)/1.WebHost/ack/wwwroot/js 디렉토리에 번들링

syn.uicontrols.js 공통 스크립트 디렉토리 구조

$(HANDSTACK_SRC)/2.Modules/wwwroot/wwwroot/uicontrols

cd $(HANDSTACK_SRC)/2.Modules/wwwroot
npm i
gulp

$(HANDSTACK_SRC)/2.Modules/wwwroot/wwwroot/js 디렉토리에 번들링

view/ - 화면의 핵심

모듈별 업무 화면을 구성하는 HTML과 JavaScript 파일을 저장합니다.

• 예시

  • /view/TST/TST010.html (화면의 구조)
  • /view/TST/TST010.js (화면의 동작)

• 특징

  • HTML 파일과 JS 파일이 동일한 이름으로 쌍을 이룹니다.
  • 서버 기술에 의존하지 않는 순수 HTML(Plain HTML)과 Vanilla JavaScript로 개발하여 명확한 역할 분리를 지향합니다.

• 자세한 내용은 화면 개발 시작하기 문서를 참고하세요.

오픈소스 라이브러리 관리

HandStack은 libman을 사용하여 프론트엔드 라이브러리를 관리합니다.

• 설정 파일: $(HANDSTACK_SRC)/libman.json
• 설치 위치: $(HANDSTACK_SRC)/2.Modules/wwwroot/wwwroot/lib

개발 PC에서 $(HANDSTACK_SRC) 디렉토리에서 명령 프롬프트로 libman restore 를 권장합니다.

{
  "version": "1.0",
  "defaultProvider": "cdnjs",
  "libraries": [
    {
      "library": "jquery@3.7.1",
      "destination": "wwwroot/lib/jquery"
    },
    {
      "library": "bootstrap@5.3.3",
      "destination": "wwwroot/lib/bootstrap"
    }
  ]
}

디렉토리 구조 탐험하기

이제 직접 파일 탐색기를 열어 디렉토리 구조를 열고 파일을 만들어 브라우저에서 직접 확인해봅시다.

• $(HANDSTACK_SRC)/1.WebHost/ack/wwwroot 경로로 이동합니다.
• $(HANDSTACK_SRC)/2.Modules/[모듈 ID]/wwwroot 경로로 이동합니다.
• assets, css, js, view 등의 디렉토리와 그 안의 파일들을 열어보며 오늘 배운 내용과 비교해 보세요.
• 특히 view/[모듈 ID]/ 폴더 안의 HTML, JS 파일 쌍을 확인해보세요.

view 디렉토리 보안

운영 환경에서 /view 경로에 있는 업무 화면에 대한 보안을 위해 다음의 항목을 권장합니다.

• HTML, JavaScript 소스 코드 난독화
• appsettings.json 설정으로 공개 접근 제한
• 업무 모듈의 사용자 권한에 따라 조회 메뉴에 따른 접근을 제한하도록 개발

{
  "IsPermissionRoles": true,
  "PermissionRoles": [
    {
        "RoleID": "Developer",
        "ModuleID": "wwwroot",
        "ApplicationID": "view",
        "ProjectID": ".*",
        "TransactionID": ""
    },
    {
        "RoleID": "User",
        "ModuleID": "wwwroot",
        "ApplicationID": "view",
        "ProjectID": "(BOD|TST)",
        "TransactionID": ".*"
    }
  ]
}

요약 정리 및 Q&A

• wwwroot: 웹에 공개되는 모든 클라이언트 자원의 루트입니다.
• assets, css, js, img: 각 역할에 맞는 공용 리소스를 보관합니다.
• lib: libman.json으로 관리되는 외부 라이브러리가 위치합니다.
• view: 화면별 HTML + JS 파일 쌍으로 실제 애플리케이션 화면을 개발하는 핵심 공간입니다.

이 구조를 이해하면 HandStack에서 프론트엔드 개발을 더 체계적으로 진행할 수 있습니다.